/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup ArkUI_NativeModule
 * @{
 *
 * @brief 提供ArkUI在Native侧的UI能力，如UI组件创建销毁、树节点操作，属性设置，事件监听等。
 *
 * @sample [DrawableDescriptorSample](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/ArkUISample/DrawableDescriptorSample)
 *
 * @since 12
 */

/**
 * @file drawable_descriptor.h
 *
 * @brief 提供NativeDrawableDescriptor接口的类型定义。
 *
 * @library libace_ndk.z.so
 * @syscap SystemCapability.ArkUI.ArkUI.Full
 * @kit ArkUI
 * @include <arkui/drawable_descriptor.h>
 * @since 12
 */

#ifndef ARKUI_NATIVE_DRAWABLE_DESCRIPTOR_H
#define ARKUI_NATIVE_DRAWABLE_DESCRIPTOR_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定义DrawableDescriptor对象。
 *
 * @since 12
 */
typedef struct ArkUI_DrawableDescriptor ArkUI_DrawableDescriptor;

/**
 * @brief 使用Image Kit定义的Native侧的OH_PixelmapNative对象。
 *
 * @since 12
 */
struct OH_PixelmapNative;

/**
 * @brief 定义OH_PixelmapNative对象指针类型。
 *
 * @since 12
 */
typedef struct OH_PixelmapNative* OH_PixelmapNativeHandle;

/**
 * @brief 定义ArkUI native组件实例对象。
 *
 * @since 22
 */
struct ArkUI_Node;

/**
 * @brief 定义ArkUI native组件实例对象指针。
 *
 * @since 22
 */
typedef struct ArkUI_Node* ArkUI_NodeHandle;

/**
 * @brief 定义DrawableDescriptor动图控制器对象。
 *
 * @since 22
 */
typedef struct ArkUI_DrawableDescriptor_AnimationController ArkUI_DrawableDescriptor_AnimationController;

/**
 * @brief 定义DrawableDescriptor动图的播放状态。
 *
 * @since 22
 */
typedef enum {
    /** 动画初始状态。 */
    DRAWABLE_DESCRIPTOR_ANIMATION_STATUS_INITIAL = 0,
    /** 动画处于播放状态。*/
    DRAWABLE_DESCRIPTOR_ANIMATION_STATUS_RUNNING = 1,
    /** 动画处于暂停状态。*/
    DRAWABLE_DESCRIPTOR_ANIMATION_STATUS_PAUSED = 2,
    /** 动画处于停止状态。*/
    DRAWABLE_DESCRIPTOR_ANIMATION_STATUS_STOPPED = 3,
} DrawableDescriptor_AnimationStatus;

/**
 * @brief 使用PixelMap创建DrawableDescriptor对象。
 *
 * @param pixelMap PixelMap对象指针。
 * @return 返回DrawableDescriptor对象指针。
 * @since 12
 */
ArkUI_DrawableDescriptor* OH_ArkUI_DrawableDescriptor_CreateFromPixelMap(OH_PixelmapNativeHandle pixelMap);

/**
 * @brief 使用PixelMap图片数组创建DrawableDescriptor对象。
 *
 * @param array PixelMap图片数组对象指针。
 * @param size PixelMap图片数组大小。
 * @return 返回DrawableDescriptor对象指针。
 * @since 12
 */
ArkUI_DrawableDescriptor* OH_ArkUI_DrawableDescriptor_CreateFromAnimatedPixelMap(
    OH_PixelmapNativeHandle* array, int32_t size);

/**
 * @brief 销毁DrawableDescriptor对象指针。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @since 12
 */
void OH_ArkUI_DrawableDescriptor_Dispose(ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 获取PixelMap图片对象指针。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @return PixelMap对象指针。
 * @since 12
 */
OH_PixelmapNativeHandle OH_ArkUI_DrawableDescriptor_GetStaticPixelMap(ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 获取用于播放动画的PixelMap图片数组数据。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @return PixelMap图片数组指针。
 * @since 12
 */
OH_PixelmapNativeHandle* OH_ArkUI_DrawableDescriptor_GetAnimatedPixelMapArray(
    ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 获取用于播放动画的PixelMap图片数组数据。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @return PixelMap图片数组大小。
 * @since 12
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimatedPixelMapArraySize(ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 设置PixelMap图片数组播放总时长。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param duration 播放总时长，单位毫秒。
 * @since 12
 */
void OH_ArkUI_DrawableDescriptor_SetAnimationDuration(ArkUI_DrawableDescriptor* drawableDescriptor, int32_t duration);

/**
 * @brief 获取PixelMap图片数组播放总时长。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @return 播放总时长，单位毫秒。
 * @since 12
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimationDuration(ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 设置PixelMap图片数组播放次数。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param iterations 播放次数。
 * @since 12
 */
void OH_ArkUI_DrawableDescriptor_SetAnimationIteration(
    ArkUI_DrawableDescriptor* drawableDescriptor, int32_t iteration);

/**
 * @brief 获取PixelMap图片数组播放次数。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @return 播放次数。
 * @since 12
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimationIteration(ArkUI_DrawableDescriptor* drawableDescriptor);

/**
 * @brief 设置动图中的单帧播放时间。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param durations 动图中的单帧播放时间数组，单位毫秒。
 *                  不设置则按照总时间播放。设置的优先级高于duration，即同时设置了duration和frameDurations时，duration不生效。
 *                  数组大小必须与PixelMap图片数组大小相同。
 *                  每帧播放时间取值范围：[0, +∞)。
 * @param size 数组大小。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_SetAnimationFrameDurations(
    ArkUI_DrawableDescriptor* drawableDescriptor, uint32_t* durations, size_t size);

/**
 * @brief 获取动图中的单帧播放时间。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param durations 动图中的单帧播放时间数组。
 * @param size 数组大小。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimationFrameDurations(
    ArkUI_DrawableDescriptor* drawableDescriptor, uint32_t* durations, size_t* size);

/**
 * @brief 设置动图是否自动播放。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param autoPlay 是否自动播放。
 *                 1表示自动播放，0表示不自动播放。
 *                 默认值为1。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_SetAnimationAutoPlay(
    ArkUI_DrawableDescriptor* drawableDescriptor, uint32_t autoPlay);

/**
 * @brief 获取动图是否自动播放。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param autoPlay 是否自动播放。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimationAutoPlay(
    ArkUI_DrawableDescriptor* drawableDescriptor, uint32_t* autoPlay);

/**
 * @brief 创建动图控制器。
 *
 * @param drawableDescriptor DrawableDescriptor对象指针。
 * @param node 组件节点指针。
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_CreateAnimationController(ArkUI_DrawableDescriptor *drawableDescriptor,
    ArkUI_NodeHandle node, ArkUI_DrawableDescriptor_AnimationController** controller);

/**
 * @brief 销毁动图控制器。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @since 22
 */
void OH_ArkUI_DrawableDescriptor_DisposeAnimationController(
    ArkUI_DrawableDescriptor_AnimationController* controller);

/**
 * @brief 从首帧开始播放。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_StartAnimation(ArkUI_DrawableDescriptor_AnimationController* controller);

/**
 * @brief 停止动图播放并回到首帧。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_StopAnimation(ArkUI_DrawableDescriptor_AnimationController* controller);

/**
 * @brief 从当前帧恢复动图播放。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_ResumeAnimation(ArkUI_DrawableDescriptor_AnimationController* controller);

/**
 * @brief 暂停动图的播放，保持在当前帧。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_PauseAnimation(ArkUI_DrawableDescriptor_AnimationController* controller);

/**
 * @brief 获取动图的播放状态。
 *
 * @param controller DrawableDescriptor动图控制器对象指针。
 * @param status DrawableDescriptor动图的播放状态。
 * @return 错误码。
 *         {@link ARKUI_ERROR_CODE_NO_ERROR} 成功。
 *         {@link ARKUI_ERROR_CODE_PARAM_INVALID} 输入参数错误。
 * @since 22
 */
int32_t OH_ArkUI_DrawableDescriptor_GetAnimationStatus(
    ArkUI_DrawableDescriptor_AnimationController* controller, DrawableDescriptor_AnimationStatus* status);
#ifdef __cplusplus
};
#endif

#endif // ARKUI_NATIVE_DRAWABLE_DESCRIPTOR_H
/** @} */
